.TH std::ios_base::xalloc 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::ios_base::xalloc \- std::ios_base::xalloc

.SH Synopsis
   static int xalloc();

   Returns a unique (program-wide) index value that can be used to access one long and
   one void* elements in the private storage of std::ios_base by calling iword() and
   pword(). The call to xalloc does not allocate memory.

   This function is thread-safe: concurrent access by multiple threads    \fI(since C++11)\fP
   does not result in a data race.

   Effectively increments the next available unique index.

.SH Return value

   Unique integer for use as pword/iword index.

.SH Example



   Uses base class pword storage for runtime type identification of derived stream
   objects.


// Run this code

 #include <iostream>

 template<class CharT, class Traits = std::char_traits<CharT>>
 class mystream : public std::basic_ostream<CharT, Traits>
 {
 public:
     static const int xindex;

     mystream(std::basic_ostream<CharT, Traits>& ostr) :
         std::basic_ostream<CharT, Traits>(ostr.rdbuf())
     {
         this->pword(xindex) = this;
     }

     void myfn()
     {
         *this << "[special handling for mystream]";
     }
 };

 // Each specialization of mystream obtains a unique index from xalloc()
 template<class CharT, class Traits>
 const int mystream<CharT, Traits>::xindex = std::ios_base::xalloc();

 // This I/O manipulator will be able to recognize ostreams that are mystreams
 // by looking up the pointer stored in pword
 template<class CharT, class Traits>
 std::basic_ostream<CharT, Traits>& mymanip(std::basic_ostream<CharT, Traits>& os)
 {
     if (os.pword(mystream<CharT, Traits>::xindex) == &os)
         static_cast<mystream<CharT, Traits>&>(os).myfn();
     return os;
 }

 int main()
 {
     std::cout << "cout, narrow-character test " << mymanip << '\\n';

     mystream<char> myout(std::cout);
     myout << "myout, narrow-character test " << mymanip << '\\n';

     std::wcout << "wcout, wide-character test " << mymanip << '\\n';

     mystream<wchar_t> mywout(std::wcout);
     mywout << "mywout, wide-character test " << mymanip << '\\n';
 }

.SH Output:

 cout, narrow-character test
 myout, narrow-character test [special handling for mystream]
 wcout, wide-character test
 mywout, wide-character test [special handling for mystream]

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

      DR    Applied to   Behavior as published    Correct behavior
   LWG 2143 C++11      xalloc was not thread-safe made thread-safe

.SH See also

         resizes the private storage if necessary and access to the void* element at
   pword the given index
         \fI(public member function)\fP
         resizes the private storage if necessary and access to the long element at the
   iword given index
         \fI(public member function)\fP
